home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Light ROM 1
/
LIGHT-ROM 1 (Amiga Library Services)(1994).iso
/
ffdisks
/
d967.lha
/
IconTrace
/
IT.doc
< prev
next >
Wrap
Text File
|
1994-01-23
|
19KB
|
706 lines
IconTrace v2.02 User's Manual 1
IconTrace v2.02
Copyright © 1993 Peter Stuer
All rights reserved
Release date December 14, 1993
FREEWARE
User Manual
COPYRIGHT NOTICE
IconTrace software and documentation are Copyright © 1993 by
Peter Stuer. All rights reserved.
DISCLAIMER
IconTrace has proven to be stable in everyday use. The author
is not responsible for any loss of data, damages to software or
hardware that may result directly or indirectly from the use of
this program. The author reserves the right to make changes to
the software or documentation without notice.
PREFACE
This program is freeware, this means that you can copy it freely
as long as you don't ask any more money for it than a nominal
fee for copying. If you want to distribute this program you
should keep this document with it. This program cannot be used
for commercial purposes without written permission from the
author.
None of the files of the IconTrace package may be modified or
left out without permission of the author. Crunching or achiving
is allowed only if none of the IconTrace files get modified by
it.
Special permission is hereby granted to include IconTrace in
Public-Domain collections such as Fred Fish's Amiga Library.
IconTrace v2.02 User's Manual 2
Chapter 1 Introduction
1.1 What is IconTrace ?
IconTrace is a program that allows you to monitor what the
icon library is doing when you start a program using the
Workbench. It's main use lies in discovering undocumented
ToolTypes and debugging your existing ToolTypes by watching if
the program finds them correctly. You are also shown what icons
your programs look for.
1.2 Features of IconTrace
Currently the following functions can be monitored:
FindToolType GetIcon
GetDiskObject MatchToolValue
GetDiskObjectNew PutDiskObject
GetDefDiskObject PutDefDiskObject
PutIcon
You can specify which functions IconTrace should monitor.
IconTrace saves the trace information it gathers as session
history. It provides a scrollbar which enables you to scroll
through the session history.
IconTrace is also a commodity. You can specify a hotkey to show
or hide the output window.
IconTrace can open on any public screen.
1.3 System requirements
IconTrace should run on any Amiga system with at least 512K
RAM and one disk-drive. IconTrace requires KickStart v2.04 or
higher to run. Special care has been taken in the program design
to make the program work with 68020, 68030 and 68040 processors
without sacrificing 68000 compatibility.
IconTrace also requires the ReqTools.library v38 or higher.
ReqTools is copyright © 1992, 1993 by Nico François.
IconTrace is KickStart 3.0 compatible and aware. It will show
you some of the new features available with this version of the
operating system.
Should you have any trouble running IconTrace on your machine,
please write to me with the full specifications of your machine,
that is KickStart version, model, expansion boards etc...
1.4 About the author and the program
IconTrace v2.02 User's Manual 3
IconTrace has been created using the Macro68 Assembler and
CygnusEd Professional 3 on an Amiga A3000 25/100 with 10MB
memory. The IconTrace documentation was formatted with PRoff.
If you have suggestions or remarks about this program, or if you
find any bugs, please let me know.
When sending in bug reports, please state exactly under what
circumstances the bug occurred, what equipment was used and what
happened. If possible also try to give me enough information to
reproduce the bug. It is very difficult to find bugs when you
don't know exactly what happened.
Write to the following address:
Fido : 2:292/603.7 (Peter Stuer)
AmigaNet : 39:120/102.7 (Peter Stuer)
NLA Net : 14:200/101.7 (Peter Stuer)
UUCP : Peter.Stuer@p7.f603.n292.z2.FidoNet.Org
SnailMail: Peter Stuer
Beatrijslaan 2 bus 13
B-2050 Antwerpen L.O.
Belgium - Europe
I will also try to put the latest available version of IconTrace
on the following BBS (this may change without further notice):
Great Balls Of Fire BBS
ReqTools Support BBS
Herman Stevens
Lubbeek
ADS Distribution HUB
ABC Host Belgium
AFN Host Belgium
Tel. +32-(0)16-64.09.12
ZyXEL U1496+ 16800 BPS (N.8.1) v32bis v42bis
24-24 h.
Fido Node 2:292/603
NLA Node 14:200/101.0
AmyNet 39:120/102.0
IconTrace v2.02 User's Manual 4
Chapter 2 Using IconTrace
You can be start IconTrace from the CLI/Shell or the
Workbench. IconTrace will always check to make sure it is not
already running. If so, the copy of IT that is already running
will be notified and its window will open or come to the front.
The second copy will exit quietly.
2.1 Starting IconTrace from the Shell
To start IconTrace from the Shell simply type:
1> IconTrace
followed by a return. If you want to continue using the Shell
while IconTrace is running, you need to prepend the Run command
before IconTrace as follows:
1> run IconTrace
If IconTrace is succesful in initializing itself, you see the
IconTrace window and will start monitoring the icon.library. If
no window is displayed, consult Appendix A (Troubleshooting) for
more assistance.
2.2 Shell Startup Options
IconTrace can be started with various options. If you run
IconTrace with a questionmark (?) as argument you'll get the
argument template.
HISTORY
This option tells IconTrace how many lines of history it
should keep. Use 0 to disable the history feature. The default
number of history lines is 256.
OUTPUT
With this option you can direct the trace information to some
other AmigaDOS device of file in addition or in place of the
information being displayed in the window.
If you have a debugging terminal attached to the serial port
you could use 'IconTrace OUTPUT=AUX:' to have all trace
information appear at the terminal.
A special symbol is DEBUG. 'OUTPUT=DEBUG' will output all
trace information to the serial port at 9600 baud.
LEFT
This option specifies the left position of the IconTrace
IconTrace v2.02 User's Manual 5
output window in pixels. By default, the leftedge will be zero
(0).
TOP
This option specifies the top position of the IconTrace output
window in pixels. By default, IconTrace will open its window 1
pixel under the screen title bar.
WIDTH
This option specifies the width of the IconTrace output window
in pixels. By default, IconTrace will open a window that is as
wide as the visible width of the public screen it is appearing
on.
HEIGHT
This option specifies the height of the IconTrace output
window in screen lines. By default, IconTrace will open a
window that is as high as the visible height of the public
screen it is appearing on, without overlapping the title bar.
SCREEN
If you do not use this option, IconTrace will open on the
default public screen which is most of the times the Workbench
screen. IconTrace will try to open on the public screen whose
name is specified after this argument.
TRACE/DONTTRACE
By specifying a trace mask using the TRACE parameter you can
determine which icon.library functions IconTrace will actually
trace. The trace mask consists of a string of characters. The
function corresponding to the character will be traced. Use
the following characters (case sensitive):
A: GetIcon F: PutDiskObject
B: GetDiskObject G: PutDefDiskObject
C: GetDefDiskObject H: FindToolType
D: GetDefDiskObjectNew I: MatchToolValue
E: PutIcon
For example, TRACE=HI will only trace the icon.library
FindToolType() and MatchToolValue(). By default, IconTrace
monitors all icon.library functions it knows about.
Specifying a trace mask for DONTTRACE will make IconTrace
ignore the functions that you specify here. For example,
DONTTRACE=a will cause the GetIcon() calls not to be shown.
The DONTTRACE trace mask always takes precedence over the
TRACE trace mask.
CX_PRIORITY
IconTrace v2.02 User's Manual 6
This option allows you to specify priority relative to the
other Commodities programs. Default priority is 0.
CX_POPKEY
This option allows you to change the default hot key for
IconTrace. The default hot key is 'ralt i' (right Alt key
pressed with 'i').
CX_POPUP
If you do not want IconTrace to open its window, you can
specify the CX_POPUP switch like this: DT CX_POPUP=NO. By
default, the IconTrace window will open.
CX_ACTIVE
By specifying CX_ACTIVE=NO, IconTrace start without its
tracing code enabled. By default, tracing starts immediately.
2.3 Starting IconTrace from the Workbench
To start IconTrace from the Workbench, simply double-click
on the IconTrace icon to start the program or use the 'Execute
Command' item from the 'Workbench' menu.
2.4 Workbench Startup Options
You can specify the same options as explained in the
paragraph "Shell Startup Options" by adding tooltypes to the
IconTrace icon.
NOTE
If you use the CX_POPUP and/or the CX_ACTIVE tooltype
you must specify them with '=YES' appended to them.
For example, 'CX_POPUP=YES'. Not using them defaults
to CX_POPUP=YES and CX_ACTIVE=YES.
To change the task priority of IconTrace you can add the TOOLPRI
tooltype to the IconTrace icon. For example, adding TOOLPRI=5 will
start running IconTrace with task priority 5.
2.5 Stopping IconTrace
You can stop IconTrace at any time by sending it a break signal. If
you started IconTrace from the Shell, you can do this by pressing
Ctrl-C.
Since IconTrace is a commodity you can use the Exchange utility to
IconTrace v2.02 User's Manual 7
control it.
'Show Interface' will open the IconTrace output window
'Hide Interface' will close the IconTrace output window
The 'Active/Inactive' cycle gadget will toggle IconTrace's
activation status. When IconTrace is active it will update it's
internal history even when the output window is closed; when it is
inactive, no tracing will occur.
'Remove' will tell IconTrace to quit.
NOTE
IconTrace will try to quit immediately. If any of the
patches are still in use, it will wait until no
program uses the IconTrace patches anymore.
2.6 The Project menu
The Project menu gives you some control over IconTrace's behaviour
while it is running.
2.6.1 The Active menu item
IconTrace is 'active' when it is allowed to monitor icon.library
calls. When this menu item is checked, IconTrace is active.
2.6.2 The Clear menu item
Clears the session history and the window.
2.6.3 The Hide menu item
Does the same as the Hide gadget of the Exchange program. IconTrace
stays in memory and, depending on its activation status, continues
to trace the icon.library.
2.6.4 The Quit menu item
This causes IconTrace to try to quit. See also 'Stopping IconTrace'.
2.7 About the trace output
The information shown depends on which function is being traced
but all messages have 3 components in common:
Process Name The name of the process calling the
icon.library function.
IconTrace v2.02 User's Manual 8
Trace Info Verbose information about the function
being executed.
Result Whether the call was succesfull or not
(if applicable)
IconTrace v2.02 User's Manual 9
:::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
::::::::::::::::::::::: IconTrace HISTORY :::::::::::::::::::::::
:::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
::: Version 2.02 ::: December 14, 1993 ::::::::::::::::::::::::::
- BUG FIX: Fixed a small bug that caused high-ASCII characters
in filenames to disappear. Thanks to Stefan Ottosson for
reporting this.
- BUG FIX: The session history was not redrawn if there were less
lines in the session history than could be displayed. Thanks
to David Nouls & Bart van Assche for reporting this.
::: Version 2.01 ::: December 6, 1993 :::::::::::::::::::::::::::
- NEW: LEFT and TOP options let you specify the left and top
position of the IconTrace window. Thanks to Preben Nielsen for
suggesting this.
- NEW: IconTrace remembers the position and dimensions of its
window when it shows it window again after a 'Hide'.
- NEW: You can use the following keys to control the position of
the session history:
Cursor Up/Cursor Down 1 line up/down
Shift Cursor Up/Cursor Down 1 page up/down
Control Cursor Up/Cursor Down top/bottom
Thanks to Magnus Holmgren for suggesting this.
- NEW: To avoid using a ridiculously long TRACEMASK parameter
if you DON'T want to see the trace results of a function, I
replaced the TRACEMASK parameter with the TRACE and DONTTRACE
parameter. For more information, see the documentation.
- NEW: Brought the manual up to date.
- BUG FIX: Due to register leaking IconTrace would exit when it
reopened its window after another copy of IconTrace woke the
original up. Thanks to Rafael D'Halleweyn for reporting this.
- BUG FIX: IconTrace ignored the CXPRIORITY argument. Thanks to
Rafael D'Halleweyn for reporting this.
- BUG FIX: The broker name of IconTrace did not fit completely in
the provided space by Exchange. Thanks to Rafael D'Halleweyn
for reporting this.
- BUG FIX: Fixed a bug that could cause a lock-up of the console
device during a refresh of the history. Thanks to Bart van
Assche for helping me to track it down.
::: Version 2.00 ::: November 15, 1993 ::::::::::::::::::::::::::
- Complete rewrite.
IconTrace v2.02 User's Manual 10
- NEW: Removed the annoying delay when quitting IconTrace. Thanks
to Rafael D'Halleweyn for the suggestion.
- NEW: Added up/down gadgets to scroll up/down line by line.
- NEW: Added Clear menu item to clear the history buffer while
IconTrace is running.
- NEW: Added an Active menu item to make activating and
deactivating IconTrace on the fly easier.
- NEW: Added trace code for undocumented functions GetIcon() and
PutIcon(). Apparently, the Workbench uses these calls to get
its icons when opening Workbench windows.
NOTE: If you want to know why it takes so extremely long for the
Workbench to show a disk/drawer contents in using View By Name
mode, start IconTrace and be amazed!
- IMPROVED: Optimized some of the core routines.
::: Version 1.02 ::: June 26, 1993 ::::::::::::::::::::::::::::::
- BUG: The patch of the GetDiskObjectNew used the wrong trace
code.
- NEW: Made error reporting and failure handling more verbose.
- NEW: Improved and optimized code.
::: Version 1.01 ::: June 24, 1993 ::::::::::::::::::::::::::::::
- BUG: FindToolType trace code gave wrong results, sorry...
::: Version 1.00 ::: June 23, 1993 ::::::::::::::::::::::::::::::
- First release
Table Of Contents
IconTrace v2.02
Chapter 1 Introduction ................................ 2
1.1 What is IconTrace ? .............................. 2
1.2 Features of IconTrace ........................... 2
1.3 System requirements ............................ 2
1.4 About the author and the program ................... 2
Chapter 2 Using IconTrace .............................. 4
2.1 Starting IconTrace from the Shell ................. 4
2.2 Shell Startup Options ........................... 4
2.3 Starting IconTrace from the Workbench ............. 6
2.4 Workbench Startup Options ....................... 6
2.5 Stopping IconTrace ............................. 6
2.6 The Project menu ................................ 7
2.6.1 The Active menu item ........................ 7
2.6.2 The Clear menu item ......................... 7
2.6.3 The Hide menu item .......................... 7
2.6.4 The Quit menu item .......................... 7
2.7 About the trace output ........................... 7
Copyright © 1993 IconTrace v2.02 written by Peter Stuer
_
_ //
Thanks to \X/ Amiga for being the best computer ever !